FX Rate API Introduction

Baokim's FX (Foreign Exchange) Rate APIs enable Merchants to obtain firm quotes (firm quote), execute foreign exchange conversions, query transaction status, and look up historical exchange rates over a date range.

1. API List

API	Endpoint	Method	Purpose
Get FX Quote	/api/v1/fx/quote	POST	Get a firm (FIRM) or indicative (INDICATIVE) quote for a specific conversion need
Create Conversion	/api/v1/fx/convert	POST	Execute a conversion based on the quote_id from Get FX Quote
Get Conversion Detail	/api/v1/fx/conversion-detail	POST	Query conversion order status and details
Get Historical Rate	/api/v1/fx/historical-rate	POST	Look up historical exchange rates by date

2. Flow

The flow consists of 3 main steps:

3. Common Request Fields

Each API request contains the following fields (in addition to API-specific fields):

Parameter	Data Type	Required	Description
request_id	string(50)	Yes	Unique code identifying the request, unique per Merchant. Suggested format: MerchantCode + BK + YYYYMMDD + UniqueId. For Create Conversion, this field serves as the idempotency key.
request_time	string(19)	Yes	Time the request is sent, GMT+7 timezone. Format: YYYY-MM-DD HH:MM:SS. Deviation over ±5 minutes → rejected (code 422).
merchant_code	string(20)	Yes	Merchant code provided by Baokim before integration

4. Common Response Fields

Parameter	Data Type	Required	Description
response_code	int(4)	Yes	Result code, per Error Codes table
response_message	string(200)	Yes	Description of the result code
merchant_code	string(20)	Yes	Merchant code
data	Object / Array	Yes	Result data. On error: null (Object) or [] (Array)

Example error response:

{
  "response_code": 110,
  "response_message": "Invalid merchant code",
  "merchant_code": "MERCHANT1234",
  "data": null
}

5. Currency and Rounding Conventions

• Currency code: ISO 4217, uppercase (USD, CNY, VND…)
• VND: integer, no decimal digits
• Foreign currency: maximum 2 decimal places (e.g., USD 10.25)